kanzi::ResourceManager Class Reference

Use the resource manager to access and use resources in kzb files. More...

#include <kanzi/core.ui/resource/resource_manager.hpp>

Classes

class  AcquireTask
 Load task for a group of resources. More...
 
class  FinishingQueue
 Collection of resource loading tasks that have been already been loaded by a loader thread and are waiting to be finished by the main thread. More...
 
struct  LoadTask
 Use this base class to implement load tasks to load new resources. More...
 

Public Types

enum  MemoryStrategy { KeepInMemory, OptimizeMemory }
 Resource manager memory strategy. More...
 
typedef unordered_set< string > UrlContainer
 Container type for URL set. More...
 
typedef shared_ptr< LoadTaskLoadTaskSharedPtr
 LoadTask shared pointer type. More...
 
typedef kzsException(* ProtocolHandler) (ResourceManager *resourceManager, string_view resourceURL, string_view protocol, string_view hostname, unsigned port, string_view path, void *userData, ResourceSharedPtr &out_resource, LoadTaskSharedPtr &out_loadTask)
 Type definition for the protocol handler of the load function. More...
 
typedef function< void(ResourceManager *, string_view resourceURL, string_view protocol, string_view hostname, unsigned port, string_view path, void *userData, Resource *resource)> ProtocolResourceReloadFunction
 Type definition for the protocol handler of the reload function. More...
 
typedef vector< pair< string, KzuBinaryDirectory * > > DirectoryContainer
 Type for the directory container. More...
 
typedef vector< LoadTaskSharedPtrFinishingQueueContainer
 Container type for the finishing queue. Used internally. More...
 
typedef function< void()> AsyncAcquireFinishedCallback
 Callback function type for acquire tasks. More...
 
typedef shared_ptr< AcquireTaskAcquireTaskSharedPtr
 AcquireTask shared pointer type. More...
 
typedef unique_ptr< KzbFileKzbFilePtr
 Type for a smart pointer to a KZB file. More...
 
typedef map< string, vector< KzbFilePtr > > KzbFileDictionary
 Type for the KZB file container. More...
 
typedef vector< ResourceSharedPtrResourceContainer
 Alias for a container of resources. More...
 

Public Member Functions

 ResourceManager (KzcMemoryManager *memoryManager)
 Constructor. More...
 
 ~ResourceManager ()
 Destructor. More...
 
void initializeLoaderThreads (size_t threadCount, size_t maxPendingResources)
 Initializes the additional resource loader threads for the resource manager. More...
 
void waitForAcquireTasks ()
 Kanzi internally uses this function when application is about to lose GL context, to wait for all existing acquire tasks to finish. More...
 
void uninitializeLoaderThreads ()
 Stops and removes the loader threads. After the call, all loading happens in the main thread. More...
 
ThreadNativeHandleType getLoaderThreadHandle (size_t threadIndex)
 Gets the native handle of a loader thread. More...
 
size_t getLoaderThreadCount () const
 Gets the number of loader threads of the resource manager. More...
 
void setMaxPendingResources (size_t maxPendingResources)
 You can use this function to change the maximum number of resources that can be processed by the loading threads at the same time. More...
 
void addDirectory (KzuBinaryDirectory *directory)
 Adds a binary directory to the resource manager to be used with the kzb protocol. More...
 
KzuBinaryDirectorymergeDirectory (KzuBinaryDirectory *directory)
 Merges a binary directory with another binary directory that has the same name and that already exists in the resource manager: More...
 
void removeDirectory (KzuBinaryDirectory *directory)
 Removes a binary directory from the resource manager. More...
 
void addKzbFile (string_view fileName)
 Opens a kzb file from the file system and adds it to the list of files. More...
 
void addKzbFile (unique_ptr< KzbFile > kzbFile)
 Adds a kzb file to the list of files. More...
 
void addKzbFile (ConstByteSpan data)
 Adds a memory block as a kzb file. More...
 
unique_ptr< ReadOnlyMemoryFileopenFile (string_view url, KzbFile **kzbFile)
 Opens a handle to a resource file inside a kzb file. More...
 
KzuBinaryDirectorygetDirectory (string_view name) const
 Gets the binary directory with the given name from the resource manager. More...
 
KzuBinaryDirectoryaddDirectoryFromFile (string_view fileName)
 Adds a binary directory from a kzb file to the resource manager, which you can then use with the kzb protocol. More...
 
KzuBinaryDirectorymergeDirectoryFromFile (string_view fileName)
 Loads a binary directory from a kzb file and merges it with another binary directory with the same name that already exists in the resource manager. More...
 
DirectoryContainer::const_iterator beginDirectories () const
 Returns the iterator to the beginning of binary directories. More...
 
DirectoryContainer::const_iterator endDirectories () const
 Returns the iterator to the end of binary directories. More...
 
void invalidateAllGPUResources ()
 Kanzi internally uses this function to set all the GPU resources to undeployed state when an application loses and recreates the GL context after a pause-resume event. More...
 
void getMemoryUsage (size_t *out_resourceCount, size_t *out_cpuMemoryUsage, size_t *out_gpuMemoryUsage) const
 Calculates the memory usage summary for all resources. More...
 
size_t getAcquireTaskCount () const
 Returns the number of acquire tasks that have been started with a call to acquireResourcesAsync and have not yet been completed. More...
 
size_t getLoadQueueSize () const
 Returns the number of resource load tasks in the load queue. More...
 
DomaingetDomain () const
 Returns the domain. More...
 
void registerProtocolHandler (kzString protocol, ProtocolHandler handler, ProtocolResourceReloadFunction reloadFunction, void *userData)
 Registers a protocol handler for loading resources specified with the given resource URL protocol (scheme name). More...
 
void unregisterProtocolHandler (kzString protocol)
 Unregisters the protocol handler with the given resource URL protocol (scheme name). More...
 
bool supportsProtocolHandler (kzString protocol) const
 Checks whether the given resource URL protocol (scheme name) is registered as a protocol handler for the resource manager. More...
 
ResourceSharedPtr acquireResource (string_view url)
 Acquires a resource associated with the given URL. More...
 
ResourceSharedPtr tryAcquireResource (string_view url)
 Acquires a resource associated with the given URL, like acquireResource, but does not throw exceptions. More...
 
template<typename Type >
shared_ptr< Type > tryAcquireResource (string_view url)
 Acquires a resource associated with the given URL and casts the resource to the given type. More...
 
template<typename Type >
shared_ptr< Type > acquireResource (string_view url)
 Acquires a resource associated with the given URL and casts the resource to the given type. More...
 
void registerResource (string_view url, ResourceSharedPtr resource)
 Associates the given URL with the resource so that the next acquireResource with the URL returns the resource. More...
 
void registerLoadTask (string_view url, LoadTaskSharedPtr loadTask)
 Associates the given URL with the resource so that the next acquireResource with the URL completes the load task and returns the result. More...
 
void unregisterResource (string_view url)
 Removes the association of the given URL to a resource or a load task. More...
 
ResourceSharedPtr acquireLoadedResource (string_view url) const
 Acquires a resource associated with the given URL. More...
 
BitmapImageUniquePtr loadImage (string_view url) const
 Loads an image from the given URL. More...
 
KzcSplineloadSpline (string_view url) const
 Loads a spline from the given URL. More...
 
string getResourceURL (const Resource &resource) const
 Tries to find a URL for the given resource. More...
 
void setDefaultMemoryStrategy (MemoryStrategy resourceReleaseStrategy)
 Sets the memory release strategy for new resources. More...
 
MemoryStrategy getDefaultMemoryStrategy () const
 Gets the memory release strategy. More...
 
void purge ()
 Deletes unreferenced resources. More...
 
void update ()
 Processes resource manager load and deployment queues to progress the background tasks. More...
 
FinishingQueuegetFinishingQueue ()
 Gets the finishing queue for asynchronous loading tasks. More...
 
bool processDeploymentQueueItem ()
 Processes asynchronous loading tasks by deploying a single loaded GPU resource. More...
 
bool hasDeploymentTasks () const
 Tell if deployment queue is empty. More...
 
AcquireTaskSharedPtr acquireResourcesAsync (const UrlContainer &urls, AsyncAcquireFinishedCallback callback)
 Creates a background task that loads and deploys all resources from a set of URLs. More...
 
void wait (AcquireTask &acquireTask)
 Blocks the execution until the async acquire task finishes and calls the callback of the task (unless it has been called already). More...
 
void deployGPUResources ()
 Kanzi internally uses this function to reload all GPU resources that have been invalidated by the pause-resume event. More...
 
void setDomain (Domain *domain)
 Kanzi internally uses this function to set the domain of the resource manager when it creates a resource manager. More...
 
KzcMemoryManagergetMemoryManager () const
 Returns the memory manager. More...
 
KzuBinaryFileInfogetBinaryFileInfo (string_view url) const
 Gets the kzb file information for a file from the given URL. More...
 
KzbFilegetKzbFile (string_view hostname, size_t index=0) const
 Get the kzb file construct corresponding to the given name. More...
 
void reloadFromUrl (Resource *resource)
 Kanzi internally uses this function to reload a resource from a kzb file. More...
 
KzbFileDictionary::const_iterator beginKzbFiles () const
 Returns the iterator to the beginning of loaded KZB files. More...
 
KzbFileDictionary::const_iterator endKzbFiles () const
 Returns the iterator to the end of loaded KZB files. More...
 
void enqueueDependencies (LoadTaskSharedPtr loadTask, UrlContainer urls)
 Enqueue resource dependencies of a load task for asynchronous loading. More...
 
ResourceContainer getAllLoadedResources () const
 Get a container of all existing resources. More...
 

Static Public Member Functions

static kzString getResourcePathFromURL (kzString resourceURL)
 Kanzi internally uses this function to convert a resource URL to a resource path by dropping the protocol and project name from the path. More...
 
static kzString getRelativePathFromAbsolutePath (kzString absolutePath)
 Kanzi internally uses this function to convert an absolute path to a node to a relative path by removing the screen name part of the path. More...
 

Friends

class FinishingQueue
 
class Resource
 
class GPUResource
 
class PreviewPatcher
 

Detailed Description

Use the resource manager to access and use resources in kzb files.

The resource manager maintains kzb files and provides mechanisms to load resources from kzb files.

To access resources in a kzb file, use the kzb URL of the resource that you want to access. For example, the URL string "kzb://programmer_tutorial/Prefabs/Widget Item Prefab" refers to the resource called "Widget Item Prefab" inside the folder "Prefabs" in the kzb file of the "programmer_tutorial" project.

Acquiring resources from kzb

When you acquire a URL for the first time, the resource manager loads the resource and caches it. The next time you use the same URL, Kanzi does not load the resource again, but returns the previously loaded resource instead.

To acquire a single resource, use acquireResource:

// Set the location of the texture that you want to acquire inside the kzb file.
string_view url = "kzb://project/Textures/texture";
// Acquire the texture. Kanzi loads the texture from the kzb file and deploys it
// to the GPU. You can immediately use the returned texture.
// If the function cannot find the texture, it throws an exception.
TextureSharedPtr texture = resourceManager->acquireResource<Texture>(url);

Releasing resources

Kanzi manages the lifetime of resources with shared pointers, but to cache resources, the resource manager maintains a shared pointer to each acquired resource. This means that Kanzi does not automatically release the memory used by resources, even if you are not using those resources.

To destroy resources and release the memory used up by those resources, use purge:

// For example, get the Image node that uses a texture.
Image2DSharedPtr image = lookupSomeImage2D();
// Before you can release a resource, you must first stop using that resource.
// For example, set the Image node texture to nullptr so that that node does not use the texture anymore.
image->setImage(TextureSharedPtr());
// Release all the resources that are no longer in use. This way you free the memory
// that the texture you released used.
resourceManager->purge();

Acquiring resources asynchronously

The resource manager uses worker threads to load multiple resources simultaneously and in the background, while the application is running. You can use Application::onConfigure to specify the number of loader threads. With loader threads you can load textures, meshes, and shaders. Kanzi uses the main thread to load all other types of resources.

You can decrease the loading time of resources by first collecting the URLs of all resources and loading multiple resources simultaneously. Kanzi does this automatically for the startup screen. If you are instantiating prefabs using the API, you can use collectResourceUrls to collect the URLs and acquireResourcesAsync to acquire the resources:

// When you have a prefab template and you want to load its resources before using the prefab.
string_view prefabUrl = "kzb://project/Textures/texture";
PrefabTemplateSharedPtr prefabTemplate = resourceManager->acquireResource<PrefabTemplate>(prefabUrl);
// First, collect the URLs of resources used by the prefab that Kanzi must load...
collectResourceUrls(*prefabTemplate, urls);
// ...then start the asynchronous loading. Kanzi calls the onAsyncLoadFinished callback when it loads all of the URLs.
ResourceManager::AcquireTaskSharedPtr acquireTask = resourceManager->acquireResourcesAsync(urls, bind(&ResourceManagerSnippets::onAsyncLoadFinished, this));

If you need the results immediately, you can use wait:

// Block execution until the acquire task finishes.
resourceManager->wait(*acquireTask);
See also
collectResourceUrls, loadPrefabAsync

Managing kzb files

At application startup, Kanzi opens the kzb files that you specify in the application.cfg or in the configuration file specified by the Application::onConfigure. With the resource manager you can use addKzbFile to open additional kzb files at runtime:

// Open a kzb file from the working directory.
resourceManager->addKzbFile("project.kzb");

Acquiring resources from the file system

Besides loading resources from kzb files, you can load resources from the file system. The resource manager supports the loading of these resource types from the file system:

Kanzi determines the type of the resource it creates from the file extension, not from the file contents. You have to ensure that the files use correct extensions.

To load resources from the file system, use the file:// protocol:

// Set the location of an image file. Use "." as the project name to refer to the current working directory.
string_view url = "file://./image.png";
// Acquire the texture. Kanzi loads the texture from the kzb file and deploys it
// to the GPU. You can immediately use the returned texture.
// If the function cannot find the texture, it throws an exception.
TextureSharedPtr texture = resourceManager->acquireResource<Texture>(url);

Member Typedef Documentation

typedef unordered_set<string> kanzi::ResourceManager::UrlContainer

Container type for URL set.

LoadTask shared pointer type.

typedef kzsException(* kanzi::ResourceManager::ProtocolHandler) (ResourceManager *resourceManager, string_view resourceURL, string_view protocol, string_view hostname, unsigned port, string_view path, void *userData, ResourceSharedPtr &out_resource, LoadTaskSharedPtr &out_loadTask)

Type definition for the protocol handler of the load function.

The load function takes a resource URL and creates either a new resource or a load task that creates a new resource.

Parameters
resourceManagerThe resource manager.
resourceURLThe full URL of the resource in the form of protocol://hostname[:port]/path.
protocolExtracted protocol part of the resource URL.
hostnameExtracted hostname part of the resource URL.
portExtracted port part of the resource URL. This is 0 if the port is omitted from the URL.
pathExtracted path part of the resource URL.
userDataThe extra protocol specific data object that was stored when the protocol handler was registered.
out_resourceThe loaded resource, or nullptr.
out_loadTaskA load task for the resource, or nullptr.
Returns
Success or exception.
typedef function<void(ResourceManager*, string_view resourceURL, string_view protocol, string_view hostname, unsigned port, string_view path, void* userData, Resource* resource)> kanzi::ResourceManager::ProtocolResourceReloadFunction

Type definition for the protocol handler of the reload function.

The reload function takes a resource URL and an existing resource, and reloads the resource.

Type for the directory container.

Deprecated:
Part of the legacy kzb loading.

Container type for the finishing queue. Used internally.

Callback function type for acquire tasks.

AcquireTask shared pointer type.

Type for a smart pointer to a KZB file.

Type for the KZB file container.

Alias for a container of resources.

Member Enumeration Documentation

Resource manager memory strategy.

Enumerator
KeepInMemory 

When a resource is no longer referenced, the resource manager keeps the resource in memory until you call purge().

OptimizeMemory 

When a resource is no longer referenced, the resource manager deletes the resource and frees the (CPU and GPU) memory used by the resource.

Constructor & Destructor Documentation

kanzi::ResourceManager::ResourceManager ( KzcMemoryManager memoryManager)
explicit

Constructor.

Parameters
memoryManagerMemory manager to use.
kanzi::ResourceManager::~ResourceManager ( )

Destructor.

Member Function Documentation

void kanzi::ResourceManager::initializeLoaderThreads ( size_t  threadCount,
size_t  maxPendingResources 
)

Initializes the additional resource loader threads for the resource manager.

Do not call this function, because Kanzi automatically calls it.

Parameters
threadCountThe number of loader threads. If 0, parallel loading is disabled.
maxPendingResourcesThe maximum number of resources that can be processed by the loading threads at the same time. If set to 0, behaves as if set to threadCount + 1.
void kanzi::ResourceManager::waitForAcquireTasks ( )

Kanzi internally uses this function when application is about to lose GL context, to wait for all existing acquire tasks to finish.

void kanzi::ResourceManager::uninitializeLoaderThreads ( )

Stops and removes the loader threads. After the call, all loading happens in the main thread.

ThreadNativeHandleType kanzi::ResourceManager::getLoaderThreadHandle ( size_t  threadIndex)

Gets the native handle of a loader thread.

You can use the native handle of a thread to set the priority of that thread, or to assign that thread to a dedicated CPU core:

// You can set the application loader thread count by using ApplicationProperties::loadingThreadCount.
// To get the native handle of the first loader thread, pass to the function threadIndex 0.
size_t threadIndex = 0;
ThreadNativeHandleType handle = resourceManager->getLoaderThreadHandle(threadIndex);
// You can use the retrieved thread native handle to set priority, or assign it to a dedicated CPU core.
#if defined(_WIN32)
SetThreadPriority(static_cast<HANDLE>(handle), THREAD_PRIORITY_ABOVE_NORMAL);
#else
sched_param sch;
int policy;
pthread_getschedparam(static_cast<pthread_t>(handle), &policy, &sch);
sch.sched_priority = 99;
pthread_setschedparam(static_cast<pthread_t>(handle), policy, &sch);
#endif

Resource manager creates all its loader threads during application startup and does not add or delete loader threads during the rest of application runtime, except during shutdown. An appropriate place to adjust loader thread settings is in the Application::onStartup() overloaded function. Kanzi calls this function after the ResourceManager created its loader threads and before Kanzi starts using loader threads for loading assets from kzb files.

Parameters
threadIndexIndex of the loader thread.
Returns
Returns the native handle of the thread at threadIndex. If threadIndex is out of bounds, throws an out_of_range exception.
size_t kanzi::ResourceManager::getLoaderThreadCount ( ) const

Gets the number of loader threads of the resource manager.

Returns
The number of loader threads. If parallel loading is disabled, the function returns 0.
void kanzi::ResourceManager::setMaxPendingResources ( size_t  maxPendingResources)

You can use this function to change the maximum number of resources that can be processed by the loading threads at the same time.

Parameters
maxPendingResourcesThe maximum number of resources that can be processed by the loading threads at the same time. If set to 0, behaves as if set to threadCount + 1.
void kanzi::ResourceManager::addDirectory ( KzuBinaryDirectory directory)

Adds a binary directory to the resource manager to be used with the kzb protocol.

This transfers the ownership of the binary directory to the resource manager.

Parameters
directoryThe binary directory you want to add.
Deprecated:
Part of the legacy kzb loading. Use addKzbFile instead.
KzuBinaryDirectory* kanzi::ResourceManager::mergeDirectory ( KzuBinaryDirectory directory)

Merges a binary directory with another binary directory that has the same name and that already exists in the resource manager:

  • If a directory with the same name already exists, this function merges the directory you pass to the existing directory and destroys the directory you passed. The files in the binary directory you pass take precedence over the files with the same name in the existing directory.
  • If a binary directory with the same name does not exist, the result is the same as when you use addDirectory.
    Parameters
    directoryThe binary directory you want to merge.
    Returns
    A pointer to the merged directory.
    Deprecated:
    Part of the legacy kzb loading. Use addKzbFile instead.
void kanzi::ResourceManager::removeDirectory ( KzuBinaryDirectory directory)

Removes a binary directory from the resource manager.

Parameters
directoryThe binary directory you want to remove.
Deprecated:
Part of the legacy kzb loading.
void kanzi::ResourceManager::addKzbFile ( string_view  fileName)

Opens a kzb file from the file system and adds it to the list of files.

If this function cannot open the file you pass to it or that file is not a kzb file, the function throws an exception.

Parameters
fileNameThe name of the file to open.
void kanzi::ResourceManager::addKzbFile ( unique_ptr< KzbFile kzbFile)

Adds a kzb file to the list of files.

Parameters
kzbFileFile to add.
void kanzi::ResourceManager::addKzbFile ( ConstByteSpan  data)

Adds a memory block as a kzb file.

This function internally creates a kzb file by reading the memory block.

Parameters
dataData to add. The memory area must be readable as long as the resource manager is alive.
unique_ptr<ReadOnlyMemoryFile> kanzi::ResourceManager::openFile ( string_view  url,
KzbFile **  kzbFile 
)

Opens a handle to a resource file inside a kzb file.

You can use this handle to read data directly from the kzb file.

Parameters
urlURL of the resource.
[out]kzbFileIf the function finds the resource file, returns a pointer to the kzb file.
Returns
Handle that points to the data inside the kzb file.
KzuBinaryDirectory* kanzi::ResourceManager::getDirectory ( string_view  name) const

Gets the binary directory with the given name from the resource manager.

Returns
nullptr if the function cannot find the directory.
Deprecated:
Part of the legacy kzb loading. Use getKzbFile instead.
KzuBinaryDirectory* kanzi::ResourceManager::addDirectoryFromFile ( string_view  fileName)

Adds a binary directory from a kzb file to the resource manager, which you can then use with the kzb protocol.

The resource manager keeps the ownership of the binary directory.

Parameters
fileNamePath to the kzb file. Note that the filename can be different from the directory name stored in the kzb file. For example, file Programmer_tutorial.kzb can contain a directory named programmer_tutorial.
Returns
A pointer that is set to point to the binary directory of the loaded kzb file.
Deprecated:
Part of the legacy kzb loading. Use addKzbFile instead.
KzuBinaryDirectory* kanzi::ResourceManager::mergeDirectoryFromFile ( string_view  fileName)

Loads a binary directory from a kzb file and merges it with another binary directory with the same name that already exists in the resource manager.

See also
For details about the merge process, see mergeDirectory().
Parameters
fileNameThe name of the kzb file from which to load the binary directory.
Returns
If successful, a pointer to the merged directory, otherwise nullptr.
Deprecated:
Part of the legacy kzb loading. Use addKzbFile instead.
DirectoryContainer::const_iterator kanzi::ResourceManager::beginDirectories ( ) const
inline

Returns the iterator to the beginning of binary directories.

Deprecated:
Part of the legacy kzb loading. Use beginKzbFiles instead.
DirectoryContainer::const_iterator kanzi::ResourceManager::endDirectories ( ) const
inline

Returns the iterator to the end of binary directories.

Deprecated:
Part of the legacy kzb loading. Use endKzbFiles instead.
void kanzi::ResourceManager::invalidateAllGPUResources ( )

Kanzi internally uses this function to set all the GPU resources to undeployed state when an application loses and recreates the GL context after a pause-resume event.

void kanzi::ResourceManager::getMemoryUsage ( size_t *  out_resourceCount,
size_t *  out_cpuMemoryUsage,
size_t *  out_gpuMemoryUsage 
) const

Calculates the memory usage summary for all resources.

Parameters
out_resourceCountThe total number of resources.
out_cpuMemoryUsageEstimate for the total amount of bytes of CPU memory that the resources use.
out_gpuMemoryUsageEstimate for the total amount of bytes of GPU memory that the resources use.
size_t kanzi::ResourceManager::getAcquireTaskCount ( ) const

Returns the number of acquire tasks that have been started with a call to acquireResourcesAsync and have not yet been completed.

Each acquire task can load multiple resources.

Returns
The number of acquire tasks.
size_t kanzi::ResourceManager::getLoadQueueSize ( ) const

Returns the number of resource load tasks in the load queue.

This includes the load tasks that are waiting to be loaded and load tasks that are currently being loaded. This does not include the load tasks that are in the finishing queue.

Returns
The number of load tasks in load queue.
Domain* kanzi::ResourceManager::getDomain ( ) const

Returns the domain.

Returns
The domain.
void kanzi::ResourceManager::registerProtocolHandler ( kzString  protocol,
ProtocolHandler  handler,
ProtocolResourceReloadFunction  reloadFunction,
void *  userData 
)

Registers a protocol handler for loading resources specified with the given resource URL protocol (scheme name).

Parameters
protocolThe protocol name. For example, "http".
handlerThe protocol loader function. Kanzi calls this function when you use a URL with the given protocol, and Kanzi does not find an existing resource with that URL. This loader function creates a resource. reloadFunction The protocol reloader function. Kanzi calls this function to recreate an existing resource. Kanzi uses this function only for GPU resources when an application loses GL context in a pause-resume event.
userDataExtra data that you want to pass to the handler functions.
void kanzi::ResourceManager::unregisterProtocolHandler ( kzString  protocol)

Unregisters the protocol handler with the given resource URL protocol (scheme name).

bool kanzi::ResourceManager::supportsProtocolHandler ( kzString  protocol) const

Checks whether the given resource URL protocol (scheme name) is registered as a protocol handler for the resource manager.

Parameters
protocolThe protocol to check.
Returns
True if the protocol is registered, otherwise False.
ResourceSharedPtr kanzi::ResourceManager::acquireResource ( string_view  url)

Acquires a resource associated with the given URL.

If no resource is associated with the URL, tries to load the resource from the location specified by the URL. The URL specifies the location with a protocol and a protocol-specific path. If you already earlier acquired the resource at the given URL, this function returns a shared pointer to the already acquired resource.

The supported protocols are:

  • kzb protocol for loading resources from kzb files. For example, "kzb://programmer_tutorial/Prefabs/Widget Item Prefab". If the function cannot find the given URL in the added binary directories, the function throws an exception.
  • File protocol for loading resources from external files. For example, "file://./Icon.png".
Parameters
urlURL of the resource.
Returns
Shared pointer to the resource.
ResourceSharedPtr kanzi::ResourceManager::tryAcquireResource ( string_view  url)

Acquires a resource associated with the given URL, like acquireResource, but does not throw exceptions.

See also
acquireResource
Parameters
urlURL of the resource.
Returns
Shared pointer to the resource. If the resource does not exist, nullptr.
template<typename Type >
shared_ptr<Type> kanzi::ResourceManager::tryAcquireResource ( string_view  url)
inline

Acquires a resource associated with the given URL and casts the resource to the given type.

If the type cast fails, the function returns nullptr.

See also
acquireResource
Parameters
urlURL of the resource.
Returns
Shared pointer to the resource. If the resource does not exist, or has different type, nullptr.
template<typename Type >
shared_ptr<Type> kanzi::ResourceManager::acquireResource ( string_view  url)
inline

Acquires a resource associated with the given URL and casts the resource to the given type.

If the resource does not exist or the type cast fails, the function throws an exception.

See also
acquireResource
Parameters
urlURL of the resource.
Returns
Shared pointer to the resource.
void kanzi::ResourceManager::registerResource ( string_view  url,
ResourceSharedPtr  resource 
)

Associates the given URL with the resource so that the next acquireResource with the URL returns the resource.

You can use this function to provide a URL to a resource that you created using the API.

Parameters
urlURL of the resource.
resourceThe registered resource.
void kanzi::ResourceManager::registerLoadTask ( string_view  url,
LoadTaskSharedPtr  loadTask 
)

Associates the given URL with the resource so that the next acquireResource with the URL completes the load task and returns the result.

Parameters
urlURL of the resource.
loadTaskA load task that creates the resource at the given URL.
void kanzi::ResourceManager::unregisterResource ( string_view  url)

Removes the association of the given URL to a resource or a load task.

You can use this function to force Kanzi to recreate a resource the next time you use this URL.

Parameters
urlURL of the resource.
ResourceSharedPtr kanzi::ResourceManager::acquireLoadedResource ( string_view  url) const

Acquires a resource associated with the given URL.

If no resource is associated with the URL, does not try to load the resource.

Parameters
urlURL of the resource.
Returns
The resource that was loaded with the given URL. If no resource was loaded with the given URL, nullptr.
BitmapImageUniquePtr kanzi::ResourceManager::loadImage ( string_view  url) const

Loads an image from the given URL.

Deprecated:
Part of the legacy kzb loading.
KzcSpline* kanzi::ResourceManager::loadSpline ( string_view  url) const

Loads a spline from the given URL.

Deprecated:
Part of the legacy kzb loading.
string kanzi::ResourceManager::getResourceURL ( const Resource resource) const

Tries to find a URL for the given resource.

This function loops over all resources, so it can take a long time to complete.

Parameters
resourceThe resource.
Returns
The resource URL. If the resource does not have a registered URL, an empty string.
static kzString kanzi::ResourceManager::getResourcePathFromURL ( kzString  resourceURL)
static

Kanzi internally uses this function to convert a resource URL to a resource path by dropping the protocol and project name from the path.

For example, converts the URL "kzb://programmer_tutorial/Textures/bgr" to "Textures/bgr".

Parameters
resourceURLA resource URL.
Returns
The resource URL without protocol and project name.
static kzString kanzi::ResourceManager::getRelativePathFromAbsolutePath ( kzString  absolutePath)
static

Kanzi internally uses this function to convert an absolute path to a node to a relative path by removing the screen name part of the path.

For example, converts the path "Screen/RootPage/Viewport 2D" to "RootPage/Viewport 2D".

Parameters
absolutePathAbsolute path to a node in the tree.
Returns
Relative path to the node from the Screen node.
void kanzi::ResourceManager::setDefaultMemoryStrategy ( MemoryStrategy  resourceReleaseStrategy)

Sets the memory release strategy for new resources.

Parameters
resourceReleaseStrategyThe new memory strategy.
MemoryStrategy kanzi::ResourceManager::getDefaultMemoryStrategy ( ) const

Gets the memory release strategy.

Returns
The current memory strategy.
void kanzi::ResourceManager::purge ( )

Deletes unreferenced resources.

You can use this function to free memory. Destroys all resources that are referenced only by the resource manager.

void kanzi::ResourceManager::update ( )

Processes resource manager load and deployment queues to progress the background tasks.

Kanzi calls this function once every frame.

FinishingQueue& kanzi::ResourceManager::getFinishingQueue ( )
inline

Gets the finishing queue for asynchronous loading tasks.

You can use this to control the deployment strategy of the resources.

Returns
The finishing queue.
bool kanzi::ResourceManager::processDeploymentQueueItem ( )

Processes asynchronous loading tasks by deploying a single loaded GPU resource.

This function does not do anything if there are no active asynchronous loading tasks with loaded resources. Kanzi calls this function once every frame. Call this function periodically to ensure that asynchronous loading tasks are completed.

Returns
False if there is no asynchronously loaded resources in the deployment queue.
bool kanzi::ResourceManager::hasDeploymentTasks ( ) const

Tell if deployment queue is empty.

Returns
True if empty, otherwise False.
AcquireTaskSharedPtr kanzi::ResourceManager::acquireResourcesAsync ( const UrlContainer urls,
AsyncAcquireFinishedCallback  callback 
)

Creates a background task that loads and deploys all resources from a set of URLs.

After Kanzi loads and deploys all resources, the function calls the callback you provide.

Parameters
urlsSet of URLs for resources that you want to load.
callbackCallback function that this function calls when Kanzi loads all specified resources.
Returns
Handle to the async load task. You can pass the handle to wait to wait for the completion of the load.
void kanzi::ResourceManager::wait ( AcquireTask acquireTask)

Blocks the execution until the async acquire task finishes and calls the callback of the task (unless it has been called already).

Parameters
acquireTaskAcquire task created by acquireResourcesAsync.
void kanzi::ResourceManager::deployGPUResources ( )

Kanzi internally uses this function to reload all GPU resources that have been invalidated by the pause-resume event.

void kanzi::ResourceManager::setDomain ( Domain domain)

Kanzi internally uses this function to set the domain of the resource manager when it creates a resource manager.

KzcMemoryManager* kanzi::ResourceManager::getMemoryManager ( ) const

Returns the memory manager.

Returns
The memory manager.
KzuBinaryFileInfo* kanzi::ResourceManager::getBinaryFileInfo ( string_view  url) const

Gets the kzb file information for a file from the given URL.

Parameters
urlURL of the binary file.
Returns
Binary file information, or nullptr if URL does not point to any file.
Deprecated:
Part of the legacy kzb loading. Use openFile instead.
KzbFile* kanzi::ResourceManager::getKzbFile ( string_view  hostname,
size_t  index = 0 
) const

Get the kzb file construct corresponding to the given name.

Parameters
hostnameHostname of the kzb file.
indexIndex of the file for the given hostname, typically 0. Can be set to higher than 0 when a single hostname has multiple kzb files.
Returns
The kzb file, or nullptr if no matching kzb file is found.
void kanzi::ResourceManager::reloadFromUrl ( Resource resource)

Kanzi internally uses this function to reload a resource from a kzb file.

Parameters
resourceThe reloaded resource.
KzbFileDictionary::const_iterator kanzi::ResourceManager::beginKzbFiles ( ) const
inline

Returns the iterator to the beginning of loaded KZB files.

Returns
A const iterator to the beginning of KZB dictionary.
KzbFileDictionary::const_iterator kanzi::ResourceManager::endKzbFiles ( ) const
inline

Returns the iterator to the end of loaded KZB files.

Returns
A const iterator to the end of KZB dictionary.
void kanzi::ResourceManager::enqueueDependencies ( LoadTaskSharedPtr  loadTask,
UrlContainer  urls 
)

Enqueue resource dependencies of a load task for asynchronous loading.

Meant to be called by LoadTask::enqueueDependencies. When you call this function it informs the main thread about the dependencies of a load task, which then triggers the asynchronous loading of these dependencies.

Parameters
loadTaskThe load task requesting the dependencies.
urlsContainer of dependency URLs.
ResourceContainer kanzi::ResourceManager::getAllLoadedResources ( ) const

Get a container of all existing resources.

Returns
A container of shared_ptrs to all existing resources.

Friends And Related Function Documentation

friend class FinishingQueue
friend
friend class Resource
friend
friend class GPUResource
friend
friend class PreviewPatcher
friend

The documentation for this class was generated from the following file: